home *** CD-ROM | disk | FTP | other *** search
/ User's Choice Windows CD / User's Choice Windows CD (CMS Software)(1993).iso / utility2 / wine02bx.zip / INFO / ELISP.13 < prev    next >
Text File  |  1993-03-28  |  49KB  |  1,185 lines
  1. Info file elisp, produced by Makeinfo, -*- Text -*- from input file
  2. elisp.texi.
  3.  
  4.    This file documents GNU Emacs Lisp.
  5.  
  6.    This is edition 1.03 of the GNU Emacs Lisp Reference Manual,   for
  7. Emacs Version 18.
  8.  
  9.    Published by the Free Software Foundation, 675 Massachusetts
  10. Avenue,  Cambridge, MA 02139 USA
  11.  
  12.    Copyright (C) 1990 Free Software Foundation, Inc.
  13.  
  14.    Permission is granted to make and distribute verbatim copies of
  15. this manual provided the copyright notice and this permission notice
  16. are preserved on all copies.
  17.  
  18.    Permission is granted to copy and distribute modified versions of
  19. this manual under the conditions for verbatim copying, provided that
  20. the entire resulting derived work is distributed under the terms of a
  21. permission notice identical to this one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that this permission notice may be stated in a
  26. translation approved by the Foundation.
  27.  
  28.  
  29. 
  30. File: elisp,  Node: Minor Modes,  Next: Mode Line Format,  Prev: Major Modes,  Up: Modes
  31.  
  32. Minor Modes
  33. ===========
  34.  
  35.    A "minor mode" provides features that users may enable or disable
  36. independently of the choice of major mode.  Minor modes can be
  37. enabled individually or in combination.  Minor modes would be better
  38. named "Generally available, optional feature modes" except that such
  39. a name is unwieldy.
  40.  
  41.    A minor mode is not usually a modification of single major mode. 
  42. For example, `auto-fill-mode' and `auto-justify-mode' may be used in
  43. any major mode that permits text insertion.  To be general, a minor
  44. mode must be effectively independent of the things major modes do.
  45.  
  46.    A minor mode is often much more difficult to implement than a
  47. major mode.  One reason is that you should be able to deactivate a
  48. minor mode and restore the environment of the major mode to the state
  49. it was in before the minor mode was activated.
  50.  
  51.    Often the biggest problem in implementing a minor mode is finding
  52. a way to insert the necessary hook into the rest of Emacs.  For
  53. example, some minor modes, such as Auto Fill mode, change how text is
  54. inserted into a buffer.  Without `auto-fill-hook', Auto Fill mode
  55. would be implementable only at great pain and great cost in editing
  56. efficiency.
  57.  
  58. * Menu:
  59.  
  60. * Minor Mode Conventions::      Tips for writing a minor mode.
  61. * Limits of Minor Modes::       Minor modes are of limited generality.
  62.  
  63.  
  64. 
  65. File: elisp,  Node: Minor Mode Conventions,  Next: Limits of Minor Modes,  Prev: Minor Modes,  Up: Minor Modes
  66.  
  67. Conventions for Writing Minor Modes
  68. -----------------------------------
  69.  
  70.    There are conventions for writing minor modes just as there are
  71. for major modes.  Several of the major mode conventions apply to
  72. minor modes as well: those regarding the name of the mode
  73. initialization function, the names of global symbols, and the use of
  74. keymaps and other tables.
  75.  
  76.    In addition, there are several conventions that are specific to
  77. minor modes.
  78.  
  79.    * The minor mode should be represented by a symbol whose name ends
  80.      in `-mode'.  This symbol should be both a command to turn the
  81.      mode on or off and a variable which records whether the mode is
  82.      on.
  83.  
  84.      This variable is used in conjunction with the `minor-mode-alist'
  85.      to display the minor mode name in the mode line.  It may also be
  86.      directly responsible for controlling the features of the minor
  87.      mode.
  88.  
  89.      If you want the minor mode to be enabled separately in each
  90.      buffer, make the variable buffer-local.
  91.  
  92.    * A minor mode command should accept one optional argument.  If
  93.      the argument is `nil', the function should toggle the mode (turn
  94.      it on if it is off, and off if it is on).  Otherwise, the
  95.      function should turn the mode on if the argument is a positive
  96.      integer, a symbol, or a list whose CAR is a positive integer; it
  97.      should turn the mode off otherwise.  (This convention has not
  98.      been implemented with full consistency in Emacs version 18.)
  99.  
  100.      Here is an example taken from the definition of `overwrite-mode':
  101.  
  102.           (setq overwrite-mode
  103.                 (if (null arg) (not overwrite-mode)
  104.                   (> (prefix-numeric-value arg) 0)))
  105.  
  106.    * Add an element to `minor-mode-alist' for each minor mode (*note
  107.      Mode Line Variables::.).  This element should be a list of the
  108.      following form:
  109.  
  110.           (MODE-VARIABLE STRING)
  111.  
  112.      Here MODE-VARIABLE is the variable that indicates the enablement
  113.      of the minor mode, and STRING is a short string, starting with a
  114.      space, to represent the mode in the mode line.  These strings
  115.      must be short so that there is room for several of them at once.
  116.  
  117.      When you add an element to `minor-mode-alist', use `assq' to
  118.      check for an existing element, to avoid duplication.  For example:
  119.  
  120.           (or (assq 'leif-mode minor-mode-alist)
  121.               (setq minor-mode-alist
  122.                     (cons '(leif-mode " Leif") minor-mode-alist)))
  123.  
  124.    * If the minor mode adds new key bindings to the local keymap, you
  125.      should be able to restore the keymap to its original value when
  126.      you deactivate the minor mode.
  127.  
  128.  
  129. 
  130. File: elisp,  Node: Limits of Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
  131.  
  132. Limitations of Minor Modes
  133. --------------------------
  134.  
  135.    It is very difficult to write a minor mode that responds to
  136. arbitrary self-inserting characters.  The principal problem is that
  137. `self-insert-command', the command to insert the last key typed, is a
  138. primitive function written in C.  It does not call any hooks, except
  139. in special cases.
  140.  
  141.    Unfortunately, you cannot simply substitute your own definition of
  142. `self-insert-command' for the existing one, as you can with most
  143. functions.  This is a consequence of the way the editor command loop
  144. works: it checks whether a key is bound to `self-insert-command' and,
  145. if so, it calls the primitive `self-insert-command' function
  146. directly.  It does not check to see whether you have written another
  147. version of the function to substitute for it.  This is done for speed.
  148. (In general, if you substitute a Lisp function for a primitive, the C
  149. code within Emacs will continue to call the original primitive, but
  150. Lisp code will call your substitute Lisp function.)
  151.  
  152.    Instead of attempting to replace the function definition for
  153. `self-insert-command', you could rebind certain keys that call
  154. `self-insert-command'.  This can be made to work as long as no two
  155. minor modes try to rebind the same key.  In a minor mode that is
  156. global (affects all buffers), do the rebinding in the global map.  In
  157. a minor mode that is local to individual buffers, you will need to
  158. copy the local keymap (since it is usually shared with all the other
  159. buffers in the same major mode) and then make the change.
  160.  
  161.  
  162. 
  163. File: elisp,  Node: Mode Line Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
  164.  
  165. Mode Line Format
  166. ================
  167.  
  168.    Each Emacs window includes a mode line which displays status
  169. information about the buffer displayed in the window.  The mode line
  170. contains information about the buffer such as its name, associated
  171. file, depth of recursive editing, and the major and minor modes of
  172. the buffer.  This section describes how the contents of the mode line
  173. are controlled.  It is in the chapter on modes because much of the
  174. information displayed in the mode line relates to the enabled major
  175. and minor modes.
  176.  
  177.    `mode-line-format' is a buffer-local variable that holds a
  178. template used to display the mode line of the current buffer.  All
  179. windows for the same buffer use the same `mode-line-format' and the
  180. mode lines will appear the same (except perhaps for the percentage of
  181. the file scrolled off the top).
  182.  
  183.    The mode line of a window is normally updated whenever a different
  184. buffer is shown in the window, or when the buffer's modified-status
  185. changes from `nil' to `t' or vice-versa.  If you modify any of the
  186. variables referenced by `mode-line-format', you may want to force an
  187. update of the mode line so as to display the new information.  You
  188. can do this with the following expression:
  189.  
  190.      (set-buffer-modified-p (buffer-modified-p))
  191.  
  192.    The mode line is usually displayed in inverse video; see
  193. `mode-line-inverse-video' in *Note Screen Attributes::.
  194.  
  195. * Menu:
  196.  
  197. * Mode Line Data::        The data structure that controls the mode line.
  198. * Mode Line Variables::   Variables used in that data structure.
  199. * %-Constructs::          Putting information into a mode line.
  200.  
  201.  
  202. 
  203. File: elisp,  Node: Mode Line Data,  Next: Mode Line Variables,  Prev: Mode Line Format,  Up: Mode Line Format
  204.  
  205. The Data Structure of the Mode Line
  206. -----------------------------------
  207.  
  208.    The mode line contents are controlled by a data structure of
  209. lists, strings, symbols and numbers kept in the buffer-local variable
  210. `mode-line-format'.  The data structure is called a "mode line
  211. construct", and it is built in recursive fashion out of simpler mode
  212. line constructs.
  213.  
  214.  * Variable: mode-line-format
  215.      The value of this variable is a mode line construct with overall
  216.      responsibility for the mode line format.  The value of this
  217.      variable controls which other variables are used to form the
  218.      mode line text, and where they appear.
  219.  
  220.    A mode line construct may be as simple as a fixed string of text,
  221. but it usually specifies how to use other variables to construct the
  222. text.  Many of these variables are themselves defined to have mode
  223. line constructs as their values.
  224.  
  225.    The default value of `mode-line-format' incorporates the values of
  226. variables such as `mode-name' and `minor-mode-alist'.  Because of
  227. this, very few modes need to alter `mode-line-format'.  For most
  228. purposes, it is sufficient to alter the variables referenced by
  229. `mode-line-format'.
  230.  
  231.    A mode line construct may be a list, cons cell, symbol, or string.
  232. If the value is a list, each element may be a list, a cons cell, a
  233. symbol, or a string.
  234.  
  235. `STRING'
  236.      A string as a mode line construct is displayed verbatim in the
  237.      mode line except for "`%'-constructs".  Decimal digits after the
  238.      `%' specify the field width for space filling on the right
  239.      (i.e., the data is left justified).  *Note %-Constructs::.
  240.  
  241. `SYMBOL'
  242.      A symbol as a mode line construct stands for its value.  The
  243.      value of SYMBOL is used in place of SYMBOL unless SYMBOL is `t'
  244.      or `nil', or is void, in which case SYMBOL is ignored.
  245.  
  246.      There is one exception: if the value of SYMBOL is a string, it
  247.      is processed verbatim in that the `%'-constructs are not
  248.      recognized.
  249.  
  250. `(STRING REST...) or (LIST REST...)'
  251.      A list whose first element is a string or list, means to
  252.      concatenate all the elements.  This is the most common form of
  253.      mode line construct.
  254.  
  255. `(SYMBOL THEN ELSE)'
  256.      A list whose first element is a symbol is a conditional.  Its
  257.      meaning depends on the value of SYMBOL.  If the value is
  258.      non-`nil', the second element of the list (THEN) is processed
  259.      recursively as a mode line element.  But if the value of SYMBOL
  260.      is `nil', the third element of the list (if there is one) is
  261.      processed recursively.
  262.  
  263. `(WIDTH REST...)'
  264.      A list whose first element is an integer specifies truncation or
  265.      padding of the results of REST.  The remaining elements REST are
  266.      processed recursively as mode line constructs and concatenated
  267.      together.  Then the result is space filled (if WIDTH is
  268.      positive) or truncated (to -WIDTH columns, if WIDTH is negative)
  269.      on the right.
  270.  
  271.      For example, the usual way to show what percentage of a buffer
  272.      is above the top of the window is to use a list like this: `(-3
  273.      .  "%p")'.
  274.  
  275.    If you do alter `mode-line-format' itself, the new value should
  276. use all the same variables that are used by the default value, rather
  277. than duplicating their contents or displaying the information in
  278. another fashion.  This permits customizations made by the user, by
  279. libraries (such as `display-time') or by major modes via changes to
  280. those variables remain effective.
  281.  
  282.    Here is an example of a `mode-line-format' that might be useful
  283. for `shell-mode' since it contains the hostname and default directory.
  284.  
  285.      (setq mode-line-format
  286.        (list ""
  287.         'mode-line-modified
  288.         "%b--" 
  289.         (getenv "HOST")      ; One element is not constant.
  290.         ":" 
  291.         'default-directory
  292.         "   "
  293.         'global-mode-string
  294.         "   %[(" 'mode-name 
  295.         'minor-mode-alist 
  296.         "%n" 
  297.         'mode-line-process  
  298.         ")%]----"
  299.         '(-3 . "%p")
  300.         "-%-"))
  301.  
  302.  
  303. 
  304. File: elisp,  Node: Mode Line Variables,  Next: %-Constructs,  Prev: Mode Line Data,  Up: Mode Line Format
  305.  
  306. Variables Used in the Mode Line
  307. -------------------------------
  308.  
  309.    This section describes variables incorporated by the standard
  310. value of `mode-line-format' into the text of the mode line.  There is
  311. nothing inherently special about these variables; any other variables
  312. could have the same effects on the mode line if `mode-line-format'
  313. were changed to use them.
  314.  
  315.  * Variable: mode-line-modified
  316.      This variable holds the mode-line construct for displaying
  317.      whether the current buffer is modified.
  318.  
  319.      The default value `mode-line-modified' is `("--%1*%1*-")'.  This
  320.      means that the mode line displays `--**-' if the buffer is
  321.      modified, `----' if the buffer is not modified, and `--%%-' if
  322.      the buffer is read only.
  323.  
  324.      Changing this variable does not force an update of the mode line.
  325.  
  326.  * Variable: mode-line-buffer-identification
  327.      This variable identifies the buffer being displayed in the window.
  328.      Its default value is `Emacs: %17b', which means that it displays
  329.      `Emacs:' followed by the buffer name.  You may want to change
  330.      this in modes such as Rmail that do not behave like a "normal"
  331.      Emacs.
  332.  
  333.  * Variable: global-mode-string
  334.      This variable holds a string that is displayed in the mode line
  335.      for the use of `display-time'.  The `%M' construct substitutes
  336.      the value of `global-mode-string', but this is obsolete, since
  337.      the variable is included directly in the mode line.
  338.  
  339.  * Variable: mode-name
  340.      This buffer-local variable holds the "pretty" name of the
  341.      current buffer's major mode.  Each major mode should set this
  342.      variable so that the mode name will appear in the mode line.
  343.  
  344.  * Variable: minor-mode-alist
  345.      This variable holds an association list whose elements specify
  346.      how the mode line should indicate that a minor mode is active. 
  347.      Each element of the `minor-mode-alist' should be a two-element
  348.      list:
  349.  
  350.           (MINOR-MODE-VARIABLE MODE-LINE-STRING)
  351.  
  352.      The string MODE-LINE-STRING is included in the mode line when
  353.      the value of MINOR-MODE-VARIABLE is non-`nil' and not otherwise.
  354.      These strings should begin with spaces so that they don't run
  355.      together.  Conventionally, the MINOR-MODE-VARIABLE for a
  356.      specific mode is set to a non-`nil' value when that minor mode
  357.      is activated.
  358.  
  359.      The default value of `minor-mode-alist' is:
  360.  
  361.           minor-mode-alist
  362.           => ((abbrev-mode " Abbrev") 
  363.               (overwrite-mode " Ovwrt") 
  364.               (auto-fill-hook " Fill")         
  365.               (defining-kbd-macro " Def"))
  366.  
  367.      (Note that in version 19, `auto-fill-hook' will be renamed to
  368.      `auto-fill-function'.)
  369.  
  370.      `minor-mode-alist' is not buffer-local.  The variables mentioned
  371.      in the alist should be buffer-local if the minor mode can be
  372.      enabled separately in each buffer.
  373.  
  374.  * Variable: mode-line-process
  375.      This buffer-local variable contains the mode line information on
  376.      process status in modes used for communicating with
  377.      subprocesses.  It is displayed immediately following the major
  378.      mode name, with no intervening space.  For example, its value in
  379.      the `*shell*' buffer is `(": %s")', which allows the shell to
  380.      display its status along with the major mode as: `(Shell: run)'.
  381.      Normally this variable is `nil'.
  382.  
  383.  * Variable: default-mode-line-format
  384.      This variable holds the default `mode-line-format' for buffers
  385.      that do not override it.  This is the same as `(default-value
  386.      'mode-line-format)'.
  387.  
  388.      The default value of `default-mode-line-format' is:
  389.  
  390.           (""
  391.            mode-line-modified
  392.            mode-line-buffer-identification
  393.            "   "
  394.            global-mode-string
  395.            "   %[("
  396.            mode-name 
  397.            minor-mode-alist 
  398.            "%n" 
  399.            mode-line-process
  400.            ")%]----"
  401.            (-3 . "%p")
  402.            "-%-")
  403.  
  404.  
  405. 
  406. File: elisp,  Node: %-Constructs,  Prev: Mode Line Variables,  Up: Mode Line Format
  407.  
  408. `%'-Constructs in the Mode Line
  409. -------------------------------
  410.  
  411.    The following table lists the recognized `%'-constructs and what
  412. they mean.
  413.  
  414. `%b'
  415.      the current buffer name, using the `buffer-name' function.
  416.  
  417. `%f'
  418.      the visited file name, using the `buffer-file-name' function.
  419.  
  420. `%*'
  421.      `%' if the buffer is read only (see `buffer-read-only'); 
  422.       `*' if the buffer is modified (see `buffer-modified-p'); 
  423.       `-' otherwise.
  424.  
  425. `%s'
  426.      the status of the subprocess belonging to the current buffer,
  427.      using `process-status'.
  428.  
  429. `%p'
  430.      the percent of the buffer above the top of window, or `Top',
  431.      `Bottom' or `All'.
  432.  
  433. `%n'
  434.      `Narrow' when narrowing is in effect; nothing otherwise (see
  435.      `narrow-to-region' in *Note Narrowing::).
  436.  
  437. `%['
  438.      an indication of the depth of recursive editing levels (not
  439.      counting minibuffer levels): one `[' for each editing level.
  440.  
  441. `%]'
  442.      one `]' for each recursive editing level (not counting
  443.      minibuffer levels).
  444.  
  445. `%%'
  446.      the character `%'--this is how to include a literal `%' in a
  447.      string in which `%'-constructs are allowed.
  448.  
  449. `%-'
  450.      dashes sufficient to fill the remainder of the mode line.
  451.  
  452.    The following two `%'-constructs are still supported but are
  453. obsolete since use of the `mode-name' and `global-mode-string'
  454. variables will produce the same results.
  455.  
  456. `%m'
  457.      the value of `mode-name'.
  458.  
  459. `%M'
  460.      the value of `global-mode-string'.  Currently, only
  461.      `display-time' modifies `global-mode-string'.
  462.  
  463.  
  464. 
  465. File: elisp,  Node: Hooks,  Prev: Mode Line Format,  Up: Modes
  466.  
  467. Hooks
  468. =====
  469.  
  470.    A "hook" is a variable whose value is a "hook function" (or a list
  471. of hook functions) to be called by parts of Emacs on certain defined
  472. occasions.  The purpose of hooks is to facilitate customization, and
  473. the value of a hook is most often set up in the `.emacs' file, but it
  474. may be changed by programs.  The function or functions used in a hook
  475. may be any of the valid kinds of functions that `funcall' accepts
  476. (*note What Is a Function::.).
  477.  
  478.    Most modes run hooks as the last step of initialization.  This
  479. makes it easy for a user to customize the behavior of the mode, by
  480. overriding the local variable assignments already made by the mode. 
  481. But hooks may also be used in other contexts.  For example, the
  482. functions named by `find-file-not-found-hooks' are called whenever a
  483. file is not found by `find-file'.
  484.  
  485.    For example, you can put the following expression in your `.emacs'
  486. file if you want to turn on Auto Fill mode when in Lisp Interaction
  487. mode:
  488.  
  489.      (setq lisp-interaction-mode-hook 'turn-on-auto-fill)
  490.  
  491.    The next example shows how to use a hook to customize the way
  492. Emacs formats C code.  (People often have strong personal preferences
  493. for one format compared to another.)  Here the hook function is an
  494. anonymous lambda expression.
  495.  
  496.      (setq c-mode-hook 
  497.            (function (lambda ()
  498.                        (setq c-indent-level 4
  499.                              c-argdecl-indent 0
  500.                              c-label-offset -4
  501.                              c-continued-statement-indent 0
  502.                              c-brace-offset 0
  503.                              comment-column 40))))
  504.      
  505.      (setq c++-mode-hook c-mode-hook)
  506.  
  507.    Finally, here is an example of how to use the Text mode hook to
  508. provide a customized mode line for buffers in Text mode, displaying
  509. the default directory in addition to the standard components of the
  510. mode line.  (This may cause the mode line to run out of space if you
  511. have very long path names or display the time and load.)
  512.  
  513.      (setq text-mode-hook
  514.            (function (lambda ()
  515.                        (setq mode-line-format
  516.                              '(mode-line-modified
  517.                                "Emacs: %14b"
  518.                                "  "  
  519.                                default-directory
  520.                                " "
  521.                                global-mode-string
  522.                                "%[(" 
  523.                                mode-name 
  524.                                minor-mode-alist 
  525.                                "%n" 
  526.                                mode-line-process  
  527.                                ") %]---"
  528.                                (-3 . "%p")
  529.                                "-%-")))))
  530.  
  531.    *Note Standard Hooks::, for a list of standard hook variables.
  532.  
  533.    Most hook variables are initially void.  This has no effect on
  534. examples such as the previous ones, where the hook variable is set
  535. without reference to any previous value.  However, if you want to add
  536. an element to a hook variable which you use as a list of functions,
  537. you need to make sure the variable is not void.  Here is how to do it
  538. using `defvar':
  539.  
  540.      (defvar foo-hook nil)
  541.      (or (memq 'my-hook foo-hook)
  542.          (setq foo-hook (cons 'my-hook foo-hook)))
  543.  
  544.    At the appropriate time, Emacs uses the `run-hooks' function to
  545. run the hooks you have specified.
  546.  
  547.  * Function: run-hooks &rest HOOKVAR
  548.      This function takes one or more hook names as arguments and runs
  549.      each one in turn.  Each HOOKVAR argument should be a symbol that
  550.      is a hook variable.  These arguments are processed in the order
  551.      specified.
  552.  
  553.      If a hook variable has a non-`nil' value, that value may be a
  554.      function or a list of functions.  If the value is a function
  555.      (either a lambda expression or a symbol with a function
  556.      definition), it is called.  If it is a list, the elements are
  557.      called, in order.  The hook functions are called with no
  558.      arguments.
  559.  
  560.      For example:
  561.  
  562.           (run-hooks 'emacs-lisp-mode-hook)
  563.  
  564.      Major mode functions use this function to call any hooks defined
  565.      by the user.
  566.  
  567.  
  568. 
  569. File: elisp,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top
  570.  
  571. Documentation
  572. *************
  573.  
  574.    GNU Emacs Lisp has convenient on-line help facilities, most of
  575. which derive their information from the documentation strings
  576. associated with functions and variables.  This chapter describes how
  577. to write good documentation strings for your Lisp programs, as well
  578. as how to write programs to access documentation.
  579.  
  580.    Note that the documentation strings for Emacs are not the same
  581. thing as the Emacs manual.  Manuals have their own source files,
  582. written in the Texinfo language; documentation strings are specified
  583. in the definitions of the functions and variables they apply to.  A
  584. collection of documentation strings is not sufficient as a manual
  585. because a good manual is not organized in that fashion; it is
  586. organized in terms of topics of discussion.
  587.  
  588. * Menu:
  589.  
  590. * Documentation Basics::      Good style for doc strings.
  591.                                 Where to put them.  How Emacs stores them.
  592. * Accessing Documentation::   How Lisp programs can access doc strings.
  593. * Keys in Documentation::     Substituting current key bindings.
  594. * Describing Characters::     Making printable descriptions of
  595.                                 non-printing characters and key sequences.
  596. * Help Functions::            Subroutines used by Emacs help facilities.
  597.  
  598.  
  599. 
  600. File: elisp,  Node: Documentation Basics,  Next: Accessing Documentation,  Prev: Documentation,  Up: Documentation
  601.  
  602. Documentation Basics
  603. ====================
  604.  
  605.    A documentation string is written using the Lisp syntax for
  606. strings, with double-quote characters surrounding the text of the
  607. string.  This is because it really is a Lisp string object.  The
  608. string serves as documentation when it is written in the proper place
  609. in the definition of a function or variable.  In a function
  610. definition, the documentation string follows the argument list.  In a
  611. variable definition, the documentation string follows the initial
  612. value of the variable.
  613.  
  614.    When you write a documentation string, make the first line a
  615. complete sentence (or two complete sentences) since some commands,
  616. such as `apropos', print only the first line of a multi-line
  617. documentation string.  Also, you should not indent the second line of
  618. a documentation string, if you have one, because that looks odd when
  619. you use `C-h f' (`describe-function') or `C-h v' (`describe-variable').
  620.  
  621.    Documentation strings may contain several special substrings,
  622. which stand for key bindings to be looked up in the current keymaps
  623. when the documentation is displayed.  This allows documentation
  624. strings to refer to the keys for related commands and be accurate
  625. even when a user rearranges the key bindings.  (*Note Accessing
  626. Documentation::.)
  627.  
  628.    Within the Lisp world, a documentation string is kept with the
  629. function or variable that it describes:
  630.  
  631.    * The documentation for a function is stored in the function
  632.      definition itself (*note Lambda Expressions::.).  The function
  633.      `documentation' knows how to extract it.
  634.  
  635.    * The documentation for a variable is stored on the variable's
  636.      property list under the property name `variable-documentation'. 
  637.      The function `documentation-property' knows how to extract it.
  638.  
  639.    However, to save space, the documentation for preloaded functions
  640. and variables (including primitive functions and autoloaded
  641. functions) are stored in the `emacs/etc/DOC-VERSION' file.  Both the
  642. `documentation' and the `documentation-property' functions know how
  643. to access `emacs/etc/DOC-VERSION', and the process is transparent to
  644. the user.  In this case, the documentation string is replaced with an
  645. integer offset into the `emacs/etc/DOC-VERSION' file.  Keeping the
  646. documentation strings out of the Emacs core image saves a significant
  647. amount of space.  *Note Building Emacs::.
  648.  
  649.    For information on the uses of documentation strings, see
  650. `where-is-internal' and `describe-bindings' in *Note Global and Local
  651. Keymaps::.  Also, see *Note : (emacs)Help.
  652.  
  653.    The `emacs/etc' directory contains two utilities for printing the
  654. `emacs/etc/DOC-VERSION' file in hardcopy.  These are `sorted-doc.c'
  655. and `digest-doc.c'.
  656.  
  657.  
  658. 
  659. File: elisp,  Node: Accessing Documentation,  Next: Keys in Documentation,  Prev: Documentation Basics,  Up: Documentation
  660.  
  661. Access to Documentation Strings
  662. ===============================
  663.  
  664.  * Function: documentation-property SYMBOL PROPERTY
  665.      This function returns the documentation string that is recorded
  666.      SYMBOL's property list under property PROPERTY.  This uses the
  667.      function `get', but does more than that: it also retrieves the
  668.      string from the file `emacs/etc/DOC-VERSION' if necessary, and
  669.      runs `substitute-command-keys' to substitute the actual
  670.      (current) key bindings.
  671.  
  672.           (documentation-property 'command-line-processed
  673.              'variable-documentation)
  674.                => "t once command line has been processed"
  675.           (symbol-plist 'command-line-processed)
  676.                => (variable-documentation 188902)
  677.  
  678.  * Function: documentation FUNCTION
  679.      This function returns the documentation string of FUNCTION.  If
  680.      the documentation string is stored in the
  681.      `emacs/etc/DOC-VERSION' file, this function will access it there.
  682.  
  683.      In addition, `documentation' runs `substitute-command-keys' on
  684.      the resulting string, so the value contains the actual (current)
  685.      key bindings.
  686.  
  687.      The function `documentation' signals a `void-function' error
  688.      unless FUNCTION has a function definition.  However, FUNCTION
  689.      does not need to have a documentation string.  If there is no
  690.      documentation string, `documentation' returns `nil'.
  691.  
  692.      Here is an example of using `documentation' and
  693.      `documentation-property' to display the documentation strings
  694.      for several symbols in a `*Help*' buffer.
  695.  
  696.           (defun describe-symbols (pattern)
  697.             "Describe the Emacs Lisp symbols matching PATTERN.
  698.           All symbols that have PATTERN in their name are described
  699.           in the *Help* buffer."
  700.             (interactive "sDescribe symbols matching: ")
  701.             (let ((describe-func
  702.                    (function 
  703.                     (lambda (s)
  704.                       ;; Print description of symbol.
  705.                       (if (fboundp s)             ; It is a function.
  706.                           (princ
  707.                            (format "%s\t%s\n%s\n\n" s
  708.                                    (if (commandp s) 
  709.                                        (concat "Command: "
  710.                                                (or (mapconcat 
  711.                                                     'key-description 
  712.                                                     (where-is-internal s) 
  713.                                                     " ")))
  714.                                      "Function")
  715.                                    (or (documentation s) 
  716.                                        "not documented"))))
  717.           
  718.                       (if (boundp s)              ; It is a variable.
  719.                           (princ
  720.                            (format "%s\t%s\n%s\n\n" s
  721.                                    (if (user-variable-p s) 
  722.                                        "Option " "Variable")
  723.                                    (or (documentation-property 
  724.                                          s 'variable-documentation)
  725.                                        "not documented")))))))
  726.                    sym-list)
  727.           
  728.               ;; Build a list of symbols that match pattern.
  729.               (mapatoms (function 
  730.                          (lambda (sym)
  731.                            (if (string-match pattern (symbol-name sym))
  732.                                (setq sym-list (cons sym sym-list))))))
  733.           
  734.               ;; Display the data.
  735.               (with-output-to-temp-buffer "*Help*"
  736.                 (mapcar describe-func (sort sym-list 'string<))
  737.                 (print-help-return-message))))
  738.  
  739.      The `describe-symbols' function works like `apropos', but
  740.      provides more information.
  741.  
  742.           (describe-symbols "goal")
  743.           
  744.           ---------- Buffer: *Help* ----------
  745.           goal-column     Option 
  746.           *Semipermanent goal column for vertical motion, 
  747.           as set by C-x C-n, or nil.
  748.           
  749.           set-goal-column Command: C-x C-n
  750.           Set the current horizontal position as a goal for C-n and C-p.
  751.           Those commands will move to this position in the line moved to
  752.           rather than trying to keep the same horizontal position.
  753.           With a non-nil argument, clears out the goal column
  754.           so that C-n and C-p resume vertical motion.
  755.           
  756.           temporary-goal-column   Variable
  757.           Current goal column for vertical motion.
  758.           It is the column where point was at the start of current run 
  759.           of vertical motion commands.
  760.           ---------- Buffer: *Help* ----------
  761.  
  762.  * Function: Snarf-documentation FILENAME
  763.      This function is used only during Emacs initialization, just
  764.      before the runnable Emacs is dumped.  It finds the file offsets
  765.      of the documentation strings stored in the file FILENAME, and
  766.      records them in the in-core function definitions and variable
  767.      property lists in place of the actual strings.  *Note Building
  768.      Emacs::.
  769.  
  770.      The file FILENAME is found in the `emacs/etc' directory (usually
  771.      FILENAME is `"DOC-VERSION"').  When the dumped Emacs is later
  772.      executed, the same file is found in the `exec-directory' (*note
  773.      Subprocess Creation::.).
  774.  
  775.  
  776. 
  777. File: elisp,  Node: Keys in Documentation,  Next: Describing Characters,  Prev: Accessing Documentation,  Up: Documentation
  778.  
  779. Substituting Key Bindings in Documentation
  780. ==========================================
  781.  
  782.  * Function: substitute-command-keys STRING
  783.      This function returns STRING with certain special substrings
  784.      replaced by the actual (current) key bindings are listed.  This
  785.      permits the documentation to be displayed with accurate
  786.      information about key bindings.  (The key bindings may be
  787.      changed by the user between the time Emacs is built and the time
  788.      that the documentation is asked for.)
  789.  
  790.      This table lists the forms of the special substrings and what
  791.      they are replaced with:
  792.  
  793.     `\[COMMAND]'
  794.           is replaced either by a keystroke sequence that will invoke
  795.           COMMAND, or by `M-x COMMAND' if COMMAND is not bound to any
  796.           key sequence.
  797.  
  798.     `\{MAPVAR}'
  799.           is replaced by a summary (made by `describe-bindings') of
  800.           the value of MAPVAR, taken as a keymap.
  801.  
  802.     `\<MAPVAR>'
  803.           makes this call to `substitute-command-keys' use the value
  804.           of MAPVAR as the keymap for future `\[COMMAND]' substrings.
  805.           This special string does not produce any replacement text
  806.           itself; it only affects the replacements done later.
  807.  
  808.      *Note:* each `\' must be doubled when written in a string in
  809.      Emacs Lisp.
  810.  
  811.      Here are examples of the special substrings:
  812.  
  813.           (substitute-command-keys 
  814.              "To abort recursive edit, type: \\[abort-recursive-edit]")
  815.           
  816.           => "To abort recursive edit, type: C-]"
  817.           
  818.           (substitute-command-keys 
  819.              "The keys that are defined for the minibuffer here are:
  820.             \\{minibuffer-local-must-match-map}")
  821.           
  822.           => "The keys that are defined for the minibuffer here are:
  823.           
  824.           ?               minibuffer-completion-help
  825.           SPC             minibuffer-complete-word
  826.           TAB             minibuffer-complete
  827.           LFD             minibuffer-complete-and-exit
  828.           RET             minibuffer-complete-and-exit
  829.           C-g             abort-recursive-edit
  830.           "
  831.           
  832.           (substitute-command-keys
  833.              "To abort a recursive edit from the minibuffer, type\
  834.            \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
  835.           => "To abort a recursive edit from the minibuffer, type C-g."
  836.  
  837.  
  838. 
  839. File: elisp,  Node: Describing Characters,  Next: Help Functions,  Prev: Keys in Documentation,  Up: Documentation
  840.  
  841. Describing Characters for Help Messages
  842. =======================================
  843.  
  844.    These functions convert characters or strings to textual
  845. descriptions.  These descriptions are useful for including arbitrary
  846. text characters or key sequences in messages, because they convert
  847. non-printing characters to sequences of printing characters.  The
  848. description of a printing character is the character itself.
  849.  
  850.  * Function: key-description STRING
  851.      This function returns a string containing the Emacs standard
  852.      notation for the keyboard characters in STRING.  See the
  853.      examples for `single-key-description'.
  854.  
  855.  * Function: single-key-description CHARACTER
  856.      This function returns a string describing CHARACTER in the
  857.      standard Emacs notation for keyboard input.  A normal printing
  858.      character is represented by itself, but a control character
  859.      turns into a string starting with `C-', a meta character turns
  860.      into a string starting with `M-', and space, linefeed, etc. are
  861.      transformed to `SPC', `LFD', etc.
  862.  
  863.           (single-key-description ?\C-x)
  864.                => "C-x"
  865.           (key-description "\C-x \M-y \n \t \r \f123")
  866.                => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
  867.  
  868.  * Function: text-char-description CHARACTER
  869.      This function returns a string describing CHARACTER in the
  870.      standard Emacs notation for characters that appear in text--like
  871.      `single-key-description', except that that control characters
  872.      are represented with a leading caret (which is how control
  873.      characters in Emacs buffers are usually displayed).
  874.  
  875.           (text-char-description ?\C-c)
  876.                => "^C"
  877.           (text-char-description ?\M-m)
  878.                => "M-m"
  879.           (text-char-description ?\C-\M-m)
  880.                => "M-^M"
  881.  
  882.  
  883. 
  884. File: elisp,  Node: Help Functions,  Prev: Describing Characters,  Up: Documentation
  885.  
  886. Help Functions
  887. ==============
  888.  
  889.    Emacs provides a variety of on-line help functions, all accessible
  890. to the user as subcommands of the prefix `C-h'.  For more information
  891. about them, see *Note : (emacs)Help.  Here we describe some
  892. program-level interfaces to the same information.
  893.  
  894.  * Command: apropos REGEXP &optional PREDICATE NOPRINT
  895.      This function finds all symbols whose names contain a match for
  896.      the regular expression REGEXP, and returns a list of them. 
  897.      Normally it displays the symbols in a buffer named `*Help*',
  898.      each with a one-line description.  If NOPRINT is non-`nil', it
  899.      does not display them, but just returns the list.
  900.  
  901.      If PREDICATE is non-`nil', it should be a function to be called
  902.      on each symbol that has matched REGEXP.  Only symbols for which
  903.      PREDICATE returns a non-`nil' value are listed or displayed.
  904.  
  905.      When you call `apropos' interactively, it prompts for REGEXP in
  906.      the minibuffer.
  907.  
  908.      In the first of the following examples, `apropos' finds all the
  909.      symbols with names containing `exec'.  They are returned but not
  910.      displayed.  In the second example, it finds and returns only
  911.      those symbols that are also commands; in addition, they are then
  912.      displayed in the `*Help*' buffer.
  913.  
  914.           (apropos "exec" nil t)
  915.                => (Buffer-menu-execute command-execute exec-directory
  916.               exec-path execute-extended-command execute-kbd-macro
  917.               executing-kbd-macro executing-macro)
  918.           
  919.           (apropos "exec" 'commandp)
  920.                => (Buffer-menu-execute execute-extended-command)
  921.           
  922.           ---------- Buffer: *Help* ----------
  923.           Buffer-menu-execute
  924.             Function: Save and/or delete buffers marked with
  925.             M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
  926.           execute-extended-command      ESC x
  927.             Function: Read function name, then read its arguments and call it.
  928.           ---------- Buffer: *Help* ----------
  929.  
  930.      The command `C-h a' (`command-apropos') calls `apropos', but
  931.      specifies a PREDICATE to restrict the output to symbols that are
  932.      commands.  The call to `apropos' looks like this:
  933.  
  934.           (apropos string 'commandp)
  935.  
  936.  * Command: help-command
  937.      This command is not a function, but rather a symbol which is
  938.      equivalent to the keymap called `help-map'.  It is defined in
  939.      `help.el' as follows:
  940.  
  941.           (define-key global-map "\C-h" 'help-command)
  942.           (fset 'help-command help-map)
  943.  
  944.  * Variable: help-map
  945.      The value of this variable is a local keymap for characters
  946.      following the Help key, `C-h'.
  947.  
  948.  * Function: print-help-return-message &optional FUNCTION
  949.      This function builds a string which is a message explaining how
  950.      to restore the previous state of the windows after a help
  951.      command.  After building the message, it applies FUNCTION to it
  952.      if FUNCTION is non-`nil'.  Otherwise it calls `message' to
  953.      display it in the echo area.
  954.  
  955.      This function expects to be called inside a
  956.      `with-output-to-temp-buffer' special form, and expects
  957.      `standard-output' to have the value bound by that special form. 
  958.      For an example of its use, see the example in the section
  959.      describing the `documentation' function (*note Accessing
  960.      Documentation::.).
  961.  
  962.      The constructed message will have one of the forms shown below.
  963.  
  964.           ---------- Echo Area ----------
  965.           Type C-x 1 to remove help window.
  966.           ---------- Echo Area ----------
  967.           
  968.           ---------- Echo Area ----------
  969.           Type C-x 4 b RET to restore old contents of help window.
  970.           ---------- Echo Area ----------
  971.  
  972.  * Variable: help-char
  973.      The value of this variable is the character that Emacs
  974.      recognizes as meaning Help.  When Emacs reads this character
  975.      (which is usually 8, the value of `C-h'), Emacs evaluates `(eval
  976.      help-form)', and displays the result if it is a string.  If
  977.      `help-form''s value is `nil', this character is read normally.
  978.  
  979.  * Variable: help-form
  980.      The value of this variable is a form to execute when the
  981.      character `help-char' is read.  If the form returns a string,
  982.      that string is displayed.  If `help-form' is `nil', then the
  983.      help character is not recognized.
  984.  
  985.      Entry to the minibuffer binds this variable to the value of
  986.      `minibuffer-help-form'.
  987.  
  988.    The following two functions are found in the library `helper'. 
  989. They are for modes that want to provide help without relinquishing
  990. control, such as the "electric" modes.  You must load that library
  991. with `(require 'helper)' in order to use them.  Their names begin
  992. with `Helper' to distinguish them from the ordinary help functions.
  993.  
  994.  * Command: Helper-describe-bindings
  995.      This command pops up a window displaying a help buffer
  996.      containing a listing of all of the key bindings from both the
  997.      local and global keymaps.  It works by calling
  998.      `describe-bindings'.
  999.  
  1000.  * Command: Helper-help
  1001.      This command provides help for the current mode.  It prompts the
  1002.      user in the minibuffer with the message `Help (Type ? for
  1003.      further options)', and then provides assistance in finding out
  1004.      what the key bindings are, and what the mode is intended for. 
  1005.      It returns `nil'.
  1006.  
  1007.      This can be customized by changing the map `Helper-help-map'.
  1008.  
  1009.  
  1010. 
  1011. File: elisp,  Node: Files,  Next: Backups and Auto-Saving,  Prev: Documentation,  Up: Top
  1012.  
  1013. Files
  1014. *****
  1015.  
  1016.    In Emacs, you can find, create, view, save, and otherwise work
  1017. with files and file directories.  This chapter describes most of the
  1018. file-related functions of Emacs Lisp, but a few others are described
  1019. in *Note Buffers::, and those related to backups and auto-saving are
  1020. described in *Note Backups and Auto-Saving::.
  1021.  
  1022. * Menu:
  1023.  
  1024. * Visiting Files::           Reading files into Emacs buffers for editing.
  1025. * Saving Buffers::           Writing changed buffers back into files.
  1026. * Reading from Files::       Reading files into other buffers.
  1027. * Writing to Files::         Writing new files from parts of buffers.
  1028. * File Locks::               Locking and unlocking files, to prevent
  1029.                                simultaneous editing by two people.
  1030. * Information about Files::  Testing existence, accessibility, size of files.
  1031. * Contents of Directories::  Getting a list of the files in a directory.
  1032. * Changing File Attributes:: Renaming files, changing protection, etc.
  1033. * File Names::               Decomposing and expanding file names.
  1034.  
  1035.  
  1036. 
  1037. File: elisp,  Node: Visiting Files,  Next: Saving Buffers,  Prev: Files,  Up: Files
  1038.  
  1039. Visiting Files
  1040. ==============
  1041.  
  1042.    Visiting a file means reading a file into a buffer.  Once this is
  1043. done, we say that the buffer is "visiting" that file, and call the
  1044. file "the visited file" of the buffer.
  1045.  
  1046.    A file and a buffer are two different things.  A file is
  1047. information recorded permanently in the computer (unless you delete
  1048. it).  A buffer, on the other hand, is information inside of Emacs
  1049. that will vanish at the end of the editing session (or when you kill
  1050. the buffer).  Usually, a buffer contains information that you have
  1051. copied from a file; then we say the buffer is visiting that file. 
  1052. The copy in the buffer is what you modify with editing commands. 
  1053. Such changes to the buffer do not change the file; therefore, to make
  1054. the changes permanent, you must "save" the buffer, which means
  1055. copying the altered buffer contents back into the file.
  1056.  
  1057.    In spite of the distinction between files and buffers, people
  1058. often refer to a file when they mean a buffer and vice-versa. 
  1059. Indeed, we say, "I am editing a file," rather than, "I am editing a
  1060. buffer which I will soon save as a file of the same name."  Humans do
  1061. not usually need to make the distinction explicit.  When dealing with
  1062. a computer program, however, it is good to keep the distinction in
  1063. mind.
  1064.  
  1065. * Menu:
  1066.  
  1067. * Visiting Functions::         The usual interface functions for visiting.
  1068. * Subroutines of Visiting::    Lower-level subroutines that they use.
  1069.  
  1070.  
  1071. 
  1072. File: elisp,  Node: Visiting Functions,  Next: Subroutines of Visiting,  Prev: Visiting Files,  Up: Visiting Files
  1073.  
  1074. Functions for Visiting Files
  1075. ----------------------------
  1076.  
  1077.    This section describes the functions normally used to visit files.
  1078. For historical reasons, these functions have names starting with
  1079. `find-' rather than `visit-'.  *Note Buffer File Name::, for
  1080. functions and variables that access the visited file name of a buffer
  1081. or that find an existing buffer by its visited file name.
  1082.  
  1083.  * Command: find-file FILENAME
  1084.      This function reads the file FILENAME into a buffer and displays
  1085.      that buffer in the selected window so that the user can edit it.
  1086.  
  1087.      The body of the `find-file' function is very simple and looks
  1088.      like this:
  1089.  
  1090.           (switch-to-buffer (find-file-noselect filename))
  1091.  
  1092.      (See `switch-to-buffer' in *Note Displaying Buffers::.)
  1093.  
  1094.      When `find-file' is called interactively, it prompts for
  1095.      FILENAME in the minibuffer.
  1096.  
  1097.  * Function: find-file-noselect FILENAME
  1098.      This function is the guts of all the file-visiting functions. 
  1099.      It reads a file into a buffer and returns the buffer.  You may
  1100.      then make the buffer current or display it in a window if you
  1101.      wish, but this function does not do so.
  1102.  
  1103.      If no buffer is currently visiting FILENAME, then one is created
  1104.      and the file is visited.  If FILENAME does not exist, the buffer
  1105.      is left empty, and `find-file-noselect' displays the message
  1106.      `New file' in the echo area.
  1107.  
  1108.      If a buffer is already visiting FILENAME, then
  1109.      `find-file-noselect' uses that buffer rather than creating a new
  1110.      one.  However, it does verify that the file has not changed
  1111.      since it was last visited or saved in that buffer.  If the file
  1112.      has changed, then this function asks the user whether to reread
  1113.      the changed file.  If the user says `yes', any changes
  1114.      previously made in the buffer will be lost.
  1115.  
  1116.      The `find-file-noselect' function calls `after-find-file' after
  1117.      the file is read in (*note Subroutines of Visiting::.).  The
  1118.      `after-find-file' function sets the buffer major mode, parses
  1119.      local variables, warns the user if there exists an auto-save
  1120.      file more recent than the file just visited, and finishes by
  1121.      running the functions in `find-file-hooks'.
  1122.  
  1123.      The `find-file-noselect' function returns the buffer that is
  1124.      visiting the file FILENAME.
  1125.  
  1126.           (find-file-noselect "/etc/fstab")
  1127.                => #<buffer fstab>
  1128.  
  1129.  * Command: find-alternate-file FILENAME
  1130.      This function reads the file FILENAME into a buffer and selects
  1131.      it, killing the buffer current at the time the command is run. 
  1132.      It is useful if you have visited the wrong file by mistake, so
  1133.      that you can get rid of the buffer that you did not want to
  1134.      create, at the same time as you visit the file you intended.
  1135.  
  1136.      When this function is called interactively, it prompts for
  1137.      FILENAME.
  1138.  
  1139.  * Command: find-file-other-window FILENAME
  1140.      This function visits the file FILENAME and displays its buffer
  1141.      in a window other than the selected window.  If there are two or
  1142.      more windows on the screen, then the window that is not selected
  1143.      is used.  If there is only one window, it is split.  The
  1144.      function returns `nil'.
  1145.  
  1146.      When this function is called interactively, it prompts for
  1147.      FILENAME.
  1148.  
  1149.  * Command: find-file-read-only FILENAME
  1150.      This function visits the file named FILENAME and selects its
  1151.      buffer, just like `find-file', but it marks the buffer as
  1152.      read-only.  *Note Read Only Buffers::, for related functions and
  1153.      variables.
  1154.  
  1155.      When this function is called interactively, it prompts for
  1156.      FILENAME.
  1157.  
  1158.  * Command: view-file FILENAME
  1159.      This function views FILENAME in View mode, returning to the
  1160.      previous buffer when done.  View mode is a mode that allows you
  1161.      to skim rapidly through the file but does not let you modify it.
  1162.  
  1163.      After loading the file, `view-file' calls the value of
  1164.      `view-hook' if that is non-`nil'.
  1165.  
  1166.      When this function is called interactively, it prompts for
  1167.      FILENAME.
  1168.  
  1169.  * Variable: find-file-hooks
  1170.      The value of this variable is a list of functions to be called
  1171.      after a file is visited.  The file's local-variables
  1172.      specification (if any) will have been processed before the hooks
  1173.      are run.  The buffer visiting the file is current when the hook
  1174.      functions are run.
  1175.  
  1176.  * Variable: find-file-not-found-hooks
  1177.      The value of this variable is a list of functions to be called
  1178.      when `find-file' or `find-file-noselect' is passed a nonexistent
  1179.      FILENAME.  These functions are called as soon as the error is
  1180.      detected.  `buffer-file-name' is already set up.  The functions
  1181.      are called in the order given, until one of them returns
  1182.      non-`nil'.
  1183.  
  1184.  
  1185.